---
title: Radio Group
description: Using the radio group machine in your project.
package: "@zag-js/radio-group"
---

A radio group allows users to make a single choice from a select number of
option

<Resources pkg="@zag-js/radio-group" />

<Showcase id="Radio" />

**Features**

- Syncs with `disabled` state of fieldset
- Syncs with form `reset` events
- Can programmatically set radio group value
- Can programmatically focus and blur radio items

## Installation

To use the radio machine in your project, run the following command in your
command line:

<CodeSnippet id="radio-group/installation.mdx" />

## Anatomy

To set up the radio group correctly, you'll need to understand its anatomy and
how we name its parts.

> Each part includes a `data-part` attribute to help identify them in the DOM.

<Anatomy id="radio-group" />

## Usage

First, import the radio group package into your project

```jsx
import * as radio from "@zag-js/radio-group"
```

The radio package exports two key functions:

- `machine` — The state machine logic for the radio widget.
- `connect` — The function that translates the machine's state to JSX attributes
  and event handlers.

> You'll also need to provide a unique `id` to the `useMachine` hook. This is
> used to ensure that every part has a unique identifier.

Next, import the required hooks and functions for your framework and use the
radio machine in your project 🔥

<CodeSnippet id="radio-group/usage.mdx" />

### Disabling the radio group

To make a radio group disabled, set the context's `disabled` property to true

```jsx {2}
const service = useMachine(radio.machine, {
  disabled: true,
})
```

### Setting the initial value

Use the `defaultValue` property to set the radio group's initial value.

```jsx {2}
const service = useMachine(radio.machine, {
  defaultValue: "apple",
})
```

### Listening for changes

When the radio group value changes, the `onValueChange` callback is invoked.

```jsx {2-7}
const service = useMachine(radio.machine, {
  onValueChange(details) {
    // details => { value: string }
    console.log("radio value is:", details.value)
  },
})
```

### Usage within forms

To use radio group within forms, use the exposed `inputProps` from the `connect`
function and ensure you pass `name` value to the machine's context. It will
render a hidden input and ensure the value changes get propagated to the form
correctly.

```jsx {2}
const service = useMachine(radio.machine, {
  name: "fruits",
})
```

## Styling guide

Earlier, we mentioned that each radio part has a `data-part` attribute added to
them to select and style them in the DOM.

### Checked State

When the radio input is checked, the `data-state` attribute is added to the

```css
[data-part="radio"][data-state="checked|unchecked"] {
  /* styles for radio checked or unchecked state */
}

[data-part="radio-control"][data-state="checked|unchecked"] {
  /* styles for radio checked or unchecked state */
}

[data-part="radio-label"][data-state="checked|unchecked"] {
  /* styles for radio checked or unchecked state */
}
```

### Focused State

When the radio input is focused, the `data-focus` attribute is added to the
root, control and label parts.

```css
[data-part="radio"][data-focus] {
  /* styles for radio focus state */
}

[data-part="radio-control"][data-focus] {
  /* styles for radio control focus state */
}

[data-part="radio-label"][data-focus] {
  /* styles for radio label focus state */
}
```

### Disabled State

When the radio is disabled, the `data-disabled` attribute is added to the root,
control and label parts.

```css
[data-part="radio"][data-disabled] {
  /* styles for radio disabled state */
}

[data-part="radio-control"][data-disabled] {
  /* styles for radio control disabled state */
}

[data-part="radio-label"][data-disabled] {
  /* styles for radio label disabled state */
}
```

### Invalid State

When the radio is invalid, the `data-invalid` attribute is added to the root,
control and label parts.

```css
[data-part="radio"][data-invalid] {
  /* styles for radio invalid state */
}

[data-part="radio-control"][data-invalid] {
  /* styles for radio control invalid state */
}

[data-part="radio-label"][data-invalid] {
  /* styles for radio label invalid state */
}
```

## Methods and Properties

### Machine Context

The radio group machine exposes the following context properties:

<ContextTable name="radio-group" />

### Machine API

The radio group `api` exposes the following methods:

<ApiTable name="radio-group" />

## Accessibility

Adheres to the
[Radio Group WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radiobutton)

### Keyboard Interactions

<KeyboardTable name="radio-group" />
